<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="UTF-8" />
<title>NASM - The Netwide Assembler</title>
<link href="nasmdoc.css" rel="stylesheet" type="text/css" />
<link href="local.css" rel="stylesheet" type="text/css" />
</head>
<body>
<ul class="navbar">
<li class="first"><a class="prev" href="nasmdoc2.html">Chapter 2</a></li>
<li><a class="next" href="nasmdoc4.html">Chapter 4</a></li>
<li><a class="toc" href="nasmdoc0.html">Contents</a></li>
<li class="last"><a class="index" href="nasmdoci.html">Index</a></li>
</ul>
<div class="title">
<h1>NASM - The Netwide Assembler</h1>
<span class="subtitle">version 2.16.03</span>
</div>
<div class="contents"
>
<h2 id="chapter-3">Chapter 3: The NASM Language</h2>
<h3 id="section-3.1">3.1 Layout of a NASM Source Line</h3>
<p>Like most assemblers, each NASM source line contains (unless it is a
macro, a preprocessor directive or an assembler directive: see
<a href="nasmdoc4.html">chapter 4</a> and <a href="nasmdoc7.html">chapter
7</a>) some combination of the four fields</p>
<pre>
label:    instruction operands        ; comment
</pre>
<p>As usual, most of these fields are optional; the presence or absence of
any combination of a label, an instruction and a comment is allowed. Of
course, the operand field is either required or forbidden by the presence
and nature of the instruction field.</p>
<p>NASM uses backslash (\) as the line continuation character; if a line
ends with backslash, the next line is considered to be a part of the
backslash-ended line.</p>
<p>NASM places no restrictions on white space within a line: labels may
have white space before them, or instructions may have no space before
them, or anything. The colon after a label is also optional. (Note that
this means that if you intend to code <code>lodsb</code> alone on a line,
and type <code>lodab</code> by accident, then that's still a valid source
line which does nothing but define a label. Running NASM with the
command-line option <code>-w+orphan-labels</code> will cause it to warn you
if you define a label alone on a line without a trailing colon.)</p>
<p>Valid characters in labels are letters, numbers, <code>_</code>,
<code>$</code>, <code>#</code>, <code>@</code>, <code>~</code>,
<code>.</code>, and <code>?</code>. The only characters which may be used
as the <em>first</em> character of an identifier are letters,
<code>.</code> (with special meaning: see <a href="#section-3.9">section
3.9</a>), <code>_</code> and <code>?</code>. An identifier may also be
prefixed with a <code>$</code> to indicate that it is intended to be read
as an identifier and not a reserved word; thus, if some other module you
are linking with defines a symbol called <code>eax</code>, you can refer to
<code>$eax</code> in NASM code to distinguish the symbol from the register.
Maximum length of an identifier is 4095 characters.</p>
<p>The instruction field may contain any machine instruction: Pentium and
P6 instructions, FPU instructions, MMX instructions and even undocumented
instructions are all supported. The instruction may be prefixed by
<code>LOCK</code>, <code>REP</code>, <code>REPE</code>/<code>REPZ</code>,
<code>REPNE</code>/<code>REPNZ</code>,
<code>XACQUIRE</code>/<code>XRELEASE</code> or
<code>BND</code>/<code>NOBND</code>, in the usual way. Explicit
address-size and operand-size prefixes <code>A16</code>, <code>A32</code>,
<code>A64</code>, <code>O16</code> and <code>O32</code>, <code>O64</code>
are provided &ndash; one example of their use is given in
<a href="nasmdo11.html">chapter 11</a>. You can also use the name of a
segment register as an instruction prefix: coding
<code>es mov [bx],ax</code> is equivalent to coding
<code>mov [es:bx],ax</code>. We recommend the latter syntax, since it is
consistent with other syntactic features of the language, but for
instructions such as <code>LODSB</code>, which has no operands and yet can
require a segment override, there is no clean syntactic way to proceed
apart from <code>es lodsb</code>.</p>
<p>An instruction is not required to use a prefix: prefixes such as
<code>CS</code>, <code>A32</code>, <code>LOCK</code> or <code>REPE</code>
can appear on a line by themselves, and NASM will just generate the prefix
bytes.</p>
<p>In addition to actual machine instructions, NASM also supports a number
of pseudo-instructions, described in <a href="#section-3.2">section
3.2</a>.</p>
<p>Instruction operands may take a number of forms: they can be registers,
described simply by the register name (e.g. <code>ax</code>,
<code>bp</code>, <code>ebx</code>, <code>cr0</code>: NASM does not use the
<code>gas</code>&ndash;style syntax in which register names must be
prefixed by a <code>%</code> sign), or they can be effective addresses (see
<a href="#section-3.3">section 3.3</a>), constants
(<a href="#section-3.4">section 3.4</a>) or expressions
(<a href="#section-3.5">section 3.5</a>).</p>
<p>For x87 floating-point instructions, NASM accepts a wide range of
syntaxes: you can use two-operand forms like MASM supports, or you can use
NASM's native single-operand forms in most cases. For example, you can
code:</p>
<pre>
        fadd    st1             ; this sets st0 := st0 + st1 
        fadd    st0,st1         ; so does this 

        fadd    st1,st0         ; this sets st1 := st1 + st0 
        fadd    to st1          ; so does this
</pre>
<p>Almost any x87 floating-point instruction that references memory must
use one of the prefixes <code>DWORD</code>, <code>QWORD</code> or
<code>TWORD</code> to indicate what size of memory operand it refers to.</p>
<h3 id="section-3.2">3.2 Pseudo-Instructions</h3>
<p>Pseudo-instructions are things which, though not real x86 machine
instructions, are used in the instruction field anyway because that's the
most convenient place to put them. The current pseudo-instructions are
<code>DB</code>, <code>DW</code>, <code>DD</code>, <code>DQ</code>,
<code>DT</code>, <code>DO</code>, <code>DY</code> and <code>DZ</code>;
their uninitialized counterparts <code>RESB</code>, <code>RESW</code>,
<code>RESD</code>, <code>RESQ</code>, <code>REST</code>, <code>RESO</code>,
<code>RESY</code> and <code>RESZ</code>; the <code>INCBIN</code> command,
the <code>EQU</code> command, and the <code>TIMES</code> prefix.</p>
<p>In this documentation, the notation "<code>D</code><em>x</em>" and
"<code>RES</code><em>x</em>" is used to indicate all the <code>DB</code>
and <code>RESB</code> type directives, respectively.</p>
<h4 id="section-3.2.1">3.2.1 <code>D</code><em>x</em>: Declaring Initialized Data</h4>
<p><code>DB</code>, <code>DW</code>, <code>DD</code>, <code>DQ</code>,
<code>DT</code>, <code>DO</code>, <code>DY</code> and <code>DZ</code>
(collectively "<code>D</code><em>x</em>" in this documentation) are used,
much as in MASM, to declare initialized data in the output file. They can
be invoked in a wide range of ways:</p>
<pre>
      db    0x55                ; just the byte 0x55 
      db    0x55,0x56,0x57      ; three bytes in succession 
      db    'a',0x55            ; character constants are OK 
      db    'hello',13,10,'$'   ; so are string constants 
      dw    0x1234              ; 0x34 0x12 
      dw    'a'                 ; 0x61 0x00 (it's just a number) 
      dw    'ab'                ; 0x61 0x62 (character constant) 
      dw    'abc'               ; 0x61 0x62 0x63 0x00 (string) 
      dd    0x12345678          ; 0x78 0x56 0x34 0x12 
      dd    1.234567e20         ; floating-point constant 
      dq    0x123456789abcdef0  ; eight byte constant 
      dq    1.234567e20         ; double-precision float 
      dt    1.234567e20         ; extended-precision float
</pre>
<p><code>DT</code>, <code>DO</code>, <code>DY</code> and <code>DZ</code> do
not accept integer numeric constants as operands.</p>
<p> Starting in NASM 2.15, a the following MASM&ndash;like features have
been implemented:</p>
<ul>
<li>
<p>A <code>?</code> argument to declare uninitialized storage:</p>
<pre>
      db    ?                   ; uninitialized
</pre>
</li>
<li>
<p>A superset of the <code>DUP</code> syntax. The NASM version of this has
the following syntax specification; capital letters indicate literal
keywords:</p>
<pre>
     dx      := DB | DW | DD | DQ | DT | DO | DY | DZ 
     type    := BYTE | WORD | DWORD | QWORD | TWORD | OWORD | YWORD | ZWORD 
     atom    := expression | string | float | '?' 
     parlist := '(' value [',' value ...] ')' 
     duplist := expression DUP [type] ['%'] parlist 
     list    := duplist | '%' parlist | type ['%'] parlist 
     value   := [type] atom | list 

     stmt    := dx value [',' value ...]
</pre>
<p>Note that a <em>list</em> needs to be prefixed with a <code>%</code>
sign unless prefixed by either <code>DUP</code> or a <em>type</em> in order
to avoid confusing it with a parenthesis starting an expression. The
following expressions are all valid:</p>
<pre>
       db 33 
       db (44)               ; Integer expression 
     ; db (44,55)            ; Invalid - error 
       db %(44,55) 
       db %('XX','YY') 
       db ('AA')             ; Integer expression - outputs single byte 
       db %('BB')            ; List, containing a string 
       db ? 
       db 6 dup (33) 
       db 6 dup (33, 34) 
       db 6 dup (33, 34), 35 
       db 7 dup (99) 
       db 7 dup dword (?, word ?, ?) 
       dw byte (?,44) 
       dw 3 dup (0xcc, 4 dup byte ('PQR'), ?), 0xabcd 
       dd 16 dup (0xaaaa, ?, 0xbbbbbb) 
       dd 64 dup (?)
</pre>
</li>
</ul>
<p> The use of <code>$</code> (current address) in a
<code>D</code><em>x</em> statement is undefined in the current version of
NASM, <em>except in the following cases</em>:</p>
<ul>
<li>
<p>For the first expression in the statement, either a <code>DUP</code> or
a data item.</p>
</li>
<li>
<p>An expression of the form "<em>value</em><code> - $</code>", which is
converted to a self-relative relocation.</p>
</li>
</ul>
<p>Future versions of NASM is likely to produce a different result or issue
an error this case.</p>
<p>There is no such restriction on using <code>$$</code> or
section-relative symbols.</p>
<h4 id="section-3.2.2">3.2.2 <code>RESB</code> and Friends: Declaring Uninitialized Data</h4>
<p><code>RESB</code>, <code>RESW</code>, <code>RESD</code>,
<code>RESQ</code>, <code>REST</code>, <code>RESO</code>, <code>RESY</code>
and <code>RESZ</code> are designed to be used in the BSS section of a
module: they declare <em>uninitialized</em> storage space. Each takes a
single operand, which is the number of bytes, words, doublewords or
whatever to reserve. The operand to a <code>RESB</code>&ndash;type
pseudo-instruction <em>would</em> be a <em>critical expression</em> (see
<a href="#section-3.8">section 3.8</a>), except that for legacy
compatibility reasons forward references are permitted, however <em>the
code will be extremely fragile and this should be considered a severe
programming error.</em> A warning will be issued; code generating this
warning should be remedied as quickly as possible (see the
<code>forward</code> class in <a href="nasmdoca.html">appendix A</a>.)</p>
<p>For example:</p>
<pre>
buffer:         resb    64              ; reserve 64 bytes 
wordvar:        resw    1               ; reserve a word 
realarray       resq    10              ; array of ten reals 
ymmval:         resy    1               ; one YMM register 
zmmvals:        resz    32              ; 32 ZMM registers
</pre>
<p> Since NASM 2.15, the MASM syntax of using <code>?</code> and
<code>DUP</code> in the <code>D</code><em>x</em> directives is also
supported. Thus, the above example could also be written:</p>
<pre>
buffer:         db      64 dup (?)      ; reserve 64 bytes 
wordvar:        dw      ?               ; reserve a word 
realarray       dq      10 dup (?)      ; array of ten reals 
ymmval:         dy      ?               ; one YMM register 
zmmvals:        dz      32 dup (?)      ; 32 ZMM registers
</pre>
<h4 id="section-3.2.3">3.2.3 <code>INCBIN</code>: Including External Binary Files</h4>
<p><code>INCBIN</code> includes binary file data verbatim into the output
file. This can be handy for (for example) including graphics and sound data
directly into a game executable file. It can be called in one of these
three ways:</p>
<pre>
    incbin  "file.dat"             ; include the whole file 
    incbin  "file.dat",1024        ; skip the first 1024 bytes 
    incbin  "file.dat",1024,512    ; skip the first 1024, and 
                                   ; actually include at most 512
</pre>
<p><code>INCBIN</code> is both a directive and a standard macro; the
standard macro version searches for the file in the include file search
path and adds the file to the dependency lists. This macro can be
overridden if desired.</p>
<h4 id="section-3.2.4">3.2.4 <code>EQU</code>: Defining Constants</h4>
<p><code>EQU</code> defines a symbol to a given constant value: when
<code>EQU</code> is used, the source line must contain a label. The action
of <code>EQU</code> is to define the given label name to the value of its
(only) operand. This definition is absolute, and cannot change later. So,
for example,</p>
<pre>
message         db      'hello, world' 
msglen          equ     $-message
</pre>
<p>defines <code>msglen</code> to be the constant 12. <code>msglen</code>
may not then be redefined later. This is not a preprocessor definition
either: the value of <code>msglen</code> is evaluated <em>once</em>, using
the value of <code>$</code> (see <a href="#section-3.5">section 3.5</a> for
an explanation of <code>$</code>) at the point of definition, rather than
being evaluated wherever it is referenced and using the value of
<code>$</code> at the point of reference.</p>
<h4 id="section-3.2.5">3.2.5 <code>TIMES</code>: Repeating Instructions or Data</h4>
<p>The <code>TIMES</code> prefix causes the instruction to be assembled
multiple times. This is partly present as NASM's equivalent of the
<code>DUP</code> syntax supported by MASM&ndash;compatible assemblers, in
that you can code</p>
<pre>
zerobuf:        times 64 db 0
</pre>
<p>or similar things; but <code>TIMES</code> is more versatile than that.
The argument to <code>TIMES</code> is not just a numeric constant, but a
numeric <em>expression</em>, so you can do things like</p>
<pre>
buffer: db      'hello, world' 
        times 64-$+buffer db ' '
</pre>
<p>which will store exactly enough spaces to make the total length of
<code>buffer</code> up to 64. Finally, <code>TIMES</code> can be applied to
ordinary instructions, so you can code trivial unrolled loops in it:</p>
<pre>
        times 100 movsb
</pre>
<p>Note that there is no effective difference between
<code>times 100 resb 1</code> and <code>resb 100</code>, except that the
latter will be assembled about 100 times faster due to the internal
structure of the assembler.</p>
<p>The operand to <code>TIMES</code> is a critical expression
(<a href="#section-3.8">section 3.8</a>).</p>
<p>Note also that <code>TIMES</code> can't be applied to macros: the reason
for this is that <code>TIMES</code> is processed after the macro phase,
which allows the argument to <code>TIMES</code> to contain expressions such
as <code>64-$+buffer</code> as above. To repeat more than one line of code,
or a complex macro, use the preprocessor <code>%rep</code> directive.</p>
<h3 id="section-3.3">3.3 Effective Addresses</h3>
<p>An effective address is any operand to an instruction which references
memory. Effective addresses, in NASM, have a very simple syntax: they
consist of an expression evaluating to the desired address, enclosed in
square brackets. For example:</p>
<pre>
wordvar dw      123 
        mov     ax,[wordvar] 
        mov     ax,[wordvar+1] 
        mov     ax,[es:wordvar+bx]
</pre>
<p>Anything not conforming to this simple system is not a valid memory
reference in NASM, for example <code>es:wordvar[bx]</code>.</p>
<p>More complicated effective addresses, such as those involving more than
one register, work in exactly the same way:</p>
<pre>
        mov     eax,[ebx*2+ecx+offset] 
        mov     ax,[bp+di+8]
</pre>
<p>NASM is capable of doing algebra on these effective addresses, so that
things which don't necessarily <em>look</em> legal are perfectly all right:</p>
<pre>
    mov     eax,[ebx*5]             ; assembles as [ebx*4+ebx] 
    mov     eax,[label1*2-label2]   ; ie [label1+(label1-label2)]
</pre>
<p>Some forms of effective address have more than one assembled form; in
most such cases NASM will generate the smallest form it can. For example,
there are distinct assembled forms for the 32-bit effective addresses
<code>[eax*2+0]</code> and <code>[eax+eax]</code>, and NASM will generally
generate the latter on the grounds that the former requires four bytes to
store a zero offset.</p>
<p>NASM has a hinting mechanism which will cause <code>[eax+ebx]</code> and
<code>[ebx+eax]</code> to generate different opcodes; this is occasionally
useful because <code>[esi+ebp]</code> and <code>[ebp+esi]</code> have
different default segment registers.</p>
<p>However, you can force NASM to generate an effective address in a
particular form by the use of the keywords <code>BYTE</code>,
<code>WORD</code>, <code>DWORD</code> and <code>NOSPLIT</code>. If you need
<code>[eax+3]</code> to be assembled using a double-word offset field
instead of the one byte NASM will normally generate, you can code
<code>[dword eax+3]</code>. Similarly, you can force NASM to use a byte
offset for a small value which it hasn't seen on the first pass (see
<a href="#section-3.8">section 3.8</a> for an example of such a code
fragment) by using <code>[byte eax+offset]</code>. As special cases,
<code>[byte eax]</code> will code <code>[eax+0]</code> with a byte offset
of zero, and <code>[dword eax]</code> will code it with a double-word
offset of zero. The normal form, <code>[eax]</code>, will be coded with no
offset field.</p>
<p>The form described in the previous paragraph is also useful if you are
trying to access data in a 32-bit segment from within 16 bit code. For more
information on this see the section on mixed-size addressing
(<a href="nasmdo11.html#section-11.2">section 11.2</a>). In particular, if
you need to access data with a known offset that is larger than will fit in
a 16-bit value, if you don't specify that it is a dword offset, nasm will
cause the high word of the offset to be lost.</p>
<p>Similarly, NASM will split <code>[eax*2]</code> into
<code>[eax+eax]</code> because that allows the offset field to be absent
and space to be saved; in fact, it will also split
<code>[eax*2+offset]</code> into <code>[eax+eax+offset]</code>. You can
combat this behaviour by the use of the <code>NOSPLIT</code> keyword:
<code>[nosplit eax*2]</code> will force <code>[eax*2+0]</code> to be
generated literally. <code>[nosplit eax*1]</code> also has the same effect.
In another way, a split EA form <code>[0, eax*2]</code> can be used, too.
However, <code>NOSPLIT</code> in <code>[nosplit eax+eax]</code> will be
ignored because user's intention here is considered as
<code>[eax+eax]</code>.</p>
<p>In 64-bit mode, NASM will by default generate absolute addresses. The
<code>REL</code> keyword makes it produce <code>RIP</code>&ndash;relative
addresses. Since this is frequently the normally desired behaviour, see the
<code>DEFAULT</code> directive (<a href="nasmdoc7.html#section-7.2">section
7.2</a>). The keyword <code>ABS</code> overrides <code>REL</code>.</p>
<p>A new form of split effective address syntax is also supported. This is
mainly intended for mib operands as used by MPX instructions, but can be
used for any memory reference. The basic concept of this form is splitting
base and index.</p>
<pre>
     mov eax,[ebx+8,ecx*4]   ; ebx=base, ecx=index, 4=scale, 8=disp
</pre>
<p>For mib operands, there are several ways of writing effective address
depending on the tools. NASM supports all currently possible ways of mib
syntax:</p>
<pre>
     ; bndstx 
     ; next 5 lines are parsed same 
     ; base=rax, index=rbx, scale=1, displacement=3 
     bndstx [rax+0x3,rbx], bnd0      ; NASM - split EA 
     bndstx [rbx*1+rax+0x3], bnd0    ; GAS - '*1' indecates an index reg 
     bndstx [rax+rbx+3], bnd0        ; GAS - without hints 
     bndstx [rax+0x3], bnd0, rbx     ; ICC-1 
     bndstx [rax+0x3], rbx, bnd0     ; ICC-2
</pre>
<p>When broadcasting decorator is used, the opsize keyword should match the
size of each element.</p>
<pre>
     VDIVPS zmm4, zmm5, dword [rbx]{1to16}   ; single-precision float 
     VDIVPS zmm4, zmm5, zword [rbx]          ; packed 512 bit memory
</pre>
<h3 id="section-3.4">3.4 Constants</h3>
<p>NASM understands four different types of constant: numeric, character,
string and floating-point.</p>
<h4 id="section-3.4.1">3.4.1 Numeric Constants</h4>
<p>A numeric constant is simply a number. NASM allows you to specify
numbers in a variety of number bases, in a variety of ways: you can suffix
<code>H</code> or <code>X</code>, <code>D</code> or <code>T</code>,
<code>Q</code> or <code>O</code>, and <code>B</code> or <code>Y</code> for
hexadecimal, decimal, octal and binary respectively, or you can prefix
<code>0x</code>, for hexadecimal in the style of C, or you can prefix
<code>$</code> for hexadecimal in the style of Borland Pascal or Motorola
Assemblers. Note, though, that the <code>$</code> prefix does double duty
as a prefix on identifiers (see <a href="#section-3.1">section 3.1</a>), so
a hex number prefixed with a <code>$</code> sign must have a digit after
the <code>$</code> rather than a letter. In addition, current versions of
NASM accept the prefix <code>0h</code> for hexadecimal, <code>0d</code> or
<code>0t</code> for decimal, <code>0o</code> or <code>0q</code> for octal,
and <code>0b</code> or <code>0y</code> for binary. Please note that unlike
C, a <code>0</code> prefix by itself does <em>not</em> imply an octal
constant!</p>
<p>Numeric constants can have underscores (<code>_</code>) interspersed to
break up long strings.</p>
<p>Some examples (all producing exactly the same code):</p>
<pre>
        mov     ax,200          ; decimal 
        mov     ax,0200         ; still decimal 
        mov     ax,0200d        ; explicitly decimal 
        mov     ax,0d200        ; also decimal 
        mov     ax,0c8h         ; hex 
        mov     ax,$0c8         ; hex again: the 0 is required 
        mov     ax,0xc8         ; hex yet again 
        mov     ax,0hc8         ; still hex 
        mov     ax,310q         ; octal 
        mov     ax,310o         ; octal again 
        mov     ax,0o310        ; octal yet again 
        mov     ax,0q310        ; octal yet again 
        mov     ax,11001000b    ; binary 
        mov     ax,1100_1000b   ; same binary constant 
        mov     ax,1100_1000y   ; same binary constant once more 
        mov     ax,0b1100_1000  ; same binary constant yet again 
        mov     ax,0y1100_1000  ; same binary constant yet again
</pre>
<h4 id="section-3.4.2">3.4.2 Character Strings</h4>
<p>A character string consists of up to eight characters enclosed in either
single quotes (<code>'...'</code>), double quotes (<code>"..."</code>) or
backquotes (<code>`...`</code>). Single or double quotes are equivalent to
NASM (except of course that surrounding the constant with single quotes
allows double quotes to appear within it and vice versa); the contents of
those are represented verbatim. Strings enclosed in backquotes support
C-style <code>\</code>&ndash;escapes for special characters.</p>
<p>The following escape sequences are recognized by backquoted strings:</p>
<pre>
      \'          single quote (') 
      \"          double quote (") 
      \`          backquote (`) 
      \\          backslash (\) 
      \?          question mark (?) 
      \a          BEL (ASCII 7) 
      \b          BS  (ASCII 8) 
      \t          TAB (ASCII 9) 
      \n          LF  (ASCII 10) 
      \v          VT  (ASCII 11) 
      \f          FF  (ASCII 12) 
      \r          CR  (ASCII 13) 
      \e          ESC (ASCII 27) 
      \377        Up to 3 octal digits - literal byte 
      \xFF        Up to 2 hexadecimal digits - literal byte 
      \u1234      4 hexadecimal digits - Unicode character 
      \U12345678  8 hexadecimal digits - Unicode character
</pre>
<p>All other escape sequences are reserved. Note that <code>\0</code>,
meaning a <code>NUL</code> character (ASCII 0), is a special case of the
octal escape sequence.</p>
<p>Unicode characters specified with <code>\u</code> or <code>\U</code> are
converted to UTF-8. For example, the following lines are all equivalent:</p>
<pre>
      db `\u263a`            ; UTF-8 smiley face 
      db `\xe2\x98\xba`      ; UTF-8 smiley face 
      db 0E2h, 098h, 0BAh    ; UTF-8 smiley face
</pre>
<h4 id="section-3.4.3">3.4.3 Character Constants</h4>
<p>A character constant consists of a string up to eight bytes long, used
in an expression context. It is treated as if it was an integer.</p>
<p>A character constant with more than one byte will be arranged with
little-endian order in mind: if you code</p>
<pre>
          mov eax,'abcd'
</pre>
<p>then the constant generated is not <code>0x61626364</code>, but
<code>0x64636261</code>, so that if you were then to store the value into
memory, it would read <code>abcd</code> rather than <code>dcba</code>. This
is also the sense of character constants understood by the Pentium's
<code>CPUID</code> instruction.</p>
<h4 id="section-3.4.4">3.4.4 String Constants</h4>
<p>String constants are character strings used in the context of some
pseudo-instructions, namely the <code>DB</code> family and
<code>INCBIN</code> (where it represents a filename.) They are also used in
certain preprocessor directives.</p>
<p>A string constant looks like a character constant, only longer. It is
treated as a concatenation of maximum-size character constants for the
conditions. So the following are equivalent:</p>
<pre>
      db    'hello'               ; string constant 
      db    'h','e','l','l','o'   ; equivalent character constants
</pre>
<p>And the following are also equivalent:</p>
<pre>
      dd    'ninechars'           ; doubleword string constant 
      dd    'nine','char','s'     ; becomes three doublewords 
      db    'ninechars',0,0,0     ; and really looks like this
</pre>
<p>Note that when used in a string-supporting context, quoted strings are
treated as a string constants even if they are short enough to be a
character constant, because otherwise <code>db 'ab'</code> would have the
same effect as <code>db 'a'</code>, which would be silly. Similarly,
three-character or four-character constants are treated as strings when
they are operands to <code>DW</code>, and so forth.</p>
<h4 id="section-3.4.5">3.4.5 Unicode Strings</h4>
<p>The special operators <code>__?utf16?__</code>,
<code>__?utf16le?__</code>, <code>__?utf16be?__</code>,
<code>__?utf32?__</code>, <code>__?utf32le?__</code> and
<code>__?utf32be?__</code> allows definition of Unicode strings. They take
a string in UTF-8 format and converts it to UTF-16 or UTF-32, respectively.
Unless the <code>be</code> forms are specified, the output is littleendian.</p>
<p>For example:</p>
<pre>
%define u(x) __?utf16?__(x) 
%define w(x) __?utf32?__(x) 

      dw u('C:\WINDOWS'), 0       ; Pathname in UTF-16 
      dd w(`A + B = \u206a`), 0   ; String in UTF-32
</pre>
<p>The UTF operators can be applied either to strings passed to the
<code>DB</code> family instructions, or to character constants in an
expression context.</p>
<h4 id="section-3.4.6">3.4.6 Floating-Point Constants</h4>
<p>Floating-point constants are acceptable only as arguments to
<code>DB</code>, <code>DW</code>, <code>DD</code>, <code>DQ</code>,
<code>DT</code>, and <code>DO</code>, or as arguments to the special
operators <code>__?float8?__</code>, <code>__?float16?__</code>,
<code>__?bfloat16?__</code>, <code>__?float32?__</code>,
<code>__?float64?__</code>, <code>__?float80m?__</code>,
<code>__?float80e?__</code>, <code>__?float128l?__</code>, and
<code>__?float128h?__</code>. See also
<a href="nasmdoc6.html#section-6.3">section 6.3</a>.</p>
<p>Floating-point constants are expressed in the traditional form: digits,
then a period, then optionally more digits, then optionally an
<code>E</code> followed by an exponent. The period is mandatory, so that
NASM can distinguish between <code>dd 1</code>, which declares an integer
constant, and <code>dd 1.0</code> which declares a floating-point constant.</p>
<p>NASM also support C99-style hexadecimal floating-point: <code>0x</code>,
hexadecimal digits, period, optionally more hexadeximal digits, then
optionally a <code>P</code> followed by a <em>binary</em> (not hexadecimal)
exponent in decimal notation. As an extension, NASM additionally supports
the <code>0h</code> and <code>$</code> prefixes for hexadecimal, as well
binary and octal floating-point, using the <code>0b</code> or
<code>0y</code> and <code>0o</code> or <code>0q</code> prefixes,
respectively.</p>
<p>Underscores to break up groups of digits are permitted in floating-point
constants as well.</p>
<p>Some examples:</p>
<pre>
      db    -0.2                    ; "Quarter precision" 
      dw    -0.5                    ; IEEE 754r/SSE5 half precision 
      dd    1.2                     ; an easy one 
      dd    1.222_222_222           ; underscores are permitted 
      dd    0x1p+2                  ; 1.0x2^2 = 4.0 
      dq    0x1p+32                 ; 1.0x2^32 = 4 294 967 296.0 
      dq    1.e10                   ; 10 000 000 000.0 
      dq    1.e+10                  ; synonymous with 1.e10 
      dq    1.e-10                  ; 0.000 000 000 1 
      dt    3.141592653589793238462 ; pi 
      do    1.e+4000                ; IEEE 754r quad precision
</pre>
<p>The 8-bit "quarter-precision" floating-point format is
sign:exponent:mantissa = 1:4:3 with an exponent bias of 7. This appears to
be the most frequently used 8-bit floating-point format, although it is not
covered by any formal standard. This is sometimes called a "minifloat."</p>
<p>The <code>bfloat16</code> format is effectively a compressed version of
the 32-bit single precision format, with a reduced mantissa. It is
effectively the same as truncating the 32-bit format to the upper 16 bits,
except for rounding. There is no <code>D</code><em>x</em> directive that
corresponds to <code>bfloat16</code> as it obviously has the same size as
the IEEE standard 16-bit half precision format, see however
<a href="nasmdoc6.html#section-6.3">section 6.3</a>.</p>
<p>The special operators are used to produce floating-point numbers in
other contexts. They produce the binary representation of a specific
floating-point number as an integer, and can use anywhere integer constants
are used in an expression. <code>__?float80m?__</code> and
<code>__?float80e?__</code> produce the 64-bit mantissa and 16-bit exponent
of an 80-bit floating-point number, and <code>__?float128l?__</code> and
<code>__?float128h?__</code> produce the lower and upper 64-bit halves of a
128-bit floating-point number, respectively.</p>
<p>For example:</p>
<pre>
      mov    rax,__?float64?__(3.141592653589793238462)
</pre>
<p>... would assign the binary representation of pi as a 64-bit floating
point number into <code>RAX</code>. This is exactly equivalent to:</p>
<pre>
      mov    rax,0x400921fb54442d18
</pre>
<p>NASM cannot do compile-time arithmetic on floating-point constants. This
is because NASM is designed to be portable &ndash; although it always
generates code to run on x86 processors, the assembler itself can run on
any system with an ANSI C compiler. Therefore, the assembler cannot
guarantee the presence of a floating-point unit capable of handling the
Intel number formats, and so for NASM to be able to do floating arithmetic
it would have to include its own complete set of floating-point routines,
which would significantly increase the size of the assembler for very
little benefit.</p>
<p>The special tokens <code>__?Infinity?__</code>, <code>__?QNaN?__</code>
(or <code>__?NaN?__</code>) and <code>__?SNaN?__</code> can be used to
generate infinities, quiet NaNs, and signalling NaNs, respectively. These
are normally used as macros:</p>
<pre>
%define Inf __?Infinity?__ 
%define NaN __?QNaN?__ 

      dq    +1.5, -Inf, NaN         ; Double-precision constants
</pre>
<p>The <code>%use fp</code> standard macro package contains a set of
convenience macros. See <a href="nasmdoc6.html#section-6.3">section
6.3</a>.</p>
<h4 id="section-3.4.7">3.4.7 Packed BCD Constants</h4>
<p>x87-style packed BCD constants can be used in the same contexts as
80-bit floating-point numbers. They are suffixed with <code>p</code> or
prefixed with <code>0p</code>, and can include up to 18 decimal digits.</p>
<p>As with other numeric constants, underscores can be used to separate
digits.</p>
<p>For example:</p>
<pre>
      dt 12_345_678_901_245_678p 
      dt -12_345_678_901_245_678p 
      dt +0p33 
      dt 33p
</pre>
<h3 id="section-3.5">3.5 Expressions</h3>
<p>Expressions in NASM are similar in syntax to those in C. Expressions are
evaluated as 64-bit integers which are then adjusted to the appropriate
size.</p>
<p>NASM supports two special tokens in expressions, allowing calculations
to involve the current assembly position: the <code>$</code> and
<code>$$</code> tokens. <code>$</code> evaluates to the assembly position
at the beginning of the line containing the expression; so you can code an
infinite loop using <code>JMP $</code>. <code>$$</code> evaluates to the
beginning of the current section; so you can tell how far into the section
you are by using <code>($-$$)</code>.</p>
<p>The arithmetic operators provided by NASM are listed here, in increasing
order of precedence.</p>
<p>A <em>boolean</em> value is true if nonzero and false if zero. The
operators which return a boolean value always return 1 for true and 0 for
false.</p>
<h4 id="section-3.5.1">3.5.1 <code>?</code> ... <code>:</code>: Conditional Operator</h4>
<p>The syntax of this operator, similar to the C conditional operator, is:</p>
<p><em>boolean</em> <code>?</code> <em>trueval</em> <code>:</code>
<em>falseval</em></p>
<p>This operator evaluates to <em>trueval</em> if <em>boolean</em> is true,
otherwise to <em>falseval</em>.</p>
<p>Note that NASM allows <code>?</code> characters in symbol names.
Therefore, it is highly advisable to always put spaces around the
<code>?</code> and <code>:</code> characters.</p>
<h4 id="section-3.5.2">3.5.2 : <code>||</code>: Boolean OR Operator</h4>
<p>The <code>||</code> operator gives a boolean OR: it evaluates to 1 if
both sides of the expression are nonzero, otherwise 0.</p>
<h4 id="section-3.5.3">3.5.3 : <code>^^</code>: Boolean XOR Operator</h4>
<p>The <code>^^</code> operator gives a boolean XOR: it evaluates to 1 if
any one side of the expression is nonzero, otherwise 0.</p>
<h4 id="section-3.5.4">3.5.4 : <code>&amp;&amp;</code>: Boolean AND Operator</h4>
<p>The <code>&amp;&amp;</code> operator gives a boolean AND: it evaluates
to 1 if both sides of the expression is nonzero, otherwise 0.</p>
<h4 id="section-3.5.5">3.5.5 : Comparison Operators</h4>
<p>NASM supports the following comparison operators:</p>
<ul>
<li>
<p><code>=</code> or <code>==</code> compare for equality.</p>
</li>
<li>
<p><code>!=</code> or <code>&lt;&gt;</code> compare for inequality.</p>
</li>
<li>
<p><code>&lt;</code> compares signed less than.</p>
</li>
<li>
<p><code>&lt;=</code> compares signed less than or equal.</p>
</li>
<li>
<p><code>&gt;</code> compares signed greater than.</p>
</li>
<li>
<p><code>&gt;=</code> compares signed greater than or equal.</p>
</li>
</ul>
<p>These operators evaluate to 0 for false or 1 for true.</p>
<ul>
<li>
<p>&lt;=&gt; does a signed comparison, and evaluates to &ndash;1 for less
than, 0 for equal, and 1 for greater than.</p>
</li>
</ul>
<p>At this time, NASM does not provide unsigned comparison operators.</p>
<h4 id="section-3.5.6">3.5.6 <code>|</code>: Bitwise OR Operator</h4>
<p>The <code>|</code> operator gives a bitwise OR, exactly as performed by
the <code>OR</code> machine instruction.</p>
<h4 id="section-3.5.7">3.5.7 <code>^</code>: Bitwise XOR Operator</h4>
<p><code>^</code> provides the bitwise XOR operation.</p>
<h4 id="section-3.5.8">3.5.8 <code>&amp;</code>: Bitwise AND Operator</h4>
<p><code>&amp;</code> provides the bitwise AND operation.</p>
<h4 id="section-3.5.9">3.5.9 Bit Shift Operators</h4>
<p><code>&lt;&lt;</code> gives a bit-shift to the left, just as it does in
C. So <code>5&lt;&lt;3</code> evaluates to 5 times 8, or 40.
<code>&gt;&gt;</code> gives an <em>unsigned</em> (logical) bit-shift to the
right; the bits shifted in from the left are set to zero.</p>
<p><code>&lt;&lt;&lt;</code> gives a bit-shift to the left, exactly
equivalent to the <code>&lt;&lt;</code> operator; it is included for
completeness. <code>&gt;&gt;&gt;</code> gives an <em>signed</em>
(arithmetic) bit-shift to the right; the bits shifted in from the left are
filled with copies of the most significant (sign) bit.</p>
<h4 id="section-3.5.10">3.5.10 <code>+</code> and <code>-</code>: Addition and Subtraction Operators</h4>
<p>The <code>+</code> and <code>-</code> operators do perfectly ordinary
addition and subtraction.</p>
<h4 id="section-3.5.11">3.5.11 Multiplication, Division and Modulo</h4>
<p><code>*</code> is the multiplication operator.</p>
<p><code>/</code> and <code>//</code> are both division operators:
<code>/</code> is unsigned division and <code>//</code> is signed division.</p>
<p>Similarly, <code>%</code> and <code>%%</code> provide unsigned and
signed modulo operators respectively.</p>
<p>Since the <code>%</code> character is used extensively by the macro
preprocessor, you should ensure that both the signed and unsigned modulo
operators are followed by white space wherever they appear.</p>
<p>NASM, like ANSI C, provides no guarantees about the sensible operation
of the signed modulo operator. On most systems it will match the signed
division operator, such that:</p>
<pre>
     b * (a // b) + (a %% b) = a       (b != 0)
</pre>
<h4 id="section-3.5.12">3.5.12 Unary Operators</h4>
<p>The highest-priority operators in NASM's expression grammar are those
which only apply to one argument. These are:</p>
<ul>
<li>
<p><code>-</code> negates (2's complement) its operand.</p>
</li>
<li>
<p><code>+</code> does nothing; it's provided for symmetry with
<code>-</code>.</p>
</li>
<li>
<p><code>~</code> computes the bitwise negation (1's complement) of its
operand.</p>
</li>
<li>
<p><code>!</code> is the boolean negation operator. It evaluates to 1 if
the argument is 0, otherwise 0.</p>
</li>
<li>
<p><code>SEG</code> provides the segment address of its operand (explained
in more detail in <a href="#section-3.6">section 3.6</a>).</p>
</li>
<li>
<p>A set of additional operators with leading and trailing double
underscores are used to implement the <code>integer functions</code> of the
<code>ifunc</code> macro package, see
<a href="nasmdoc6.html#section-6.4">section 6.4</a>.</p>
</li>
</ul>
<h3 id="section-3.6">3.6 <code>SEG</code> and <code>WRT</code></h3>
<p>When writing large 16-bit programs, which must be split into multiple
segments, it is often necessary to be able to refer to the segment part of
the address of a symbol. NASM supports the <code>SEG</code> operator to
perform this function.</p>
<p>The <code>SEG</code> operator evaluates to the <em>preferred</em>
segment base of a symbol, defined as the segment base relative to which the
offset of the symbol makes sense. So the code</p>
<pre>
        mov     ax,seg symbol 
        mov     es,ax 
        mov     bx,symbol
</pre>
<p>will load <code>ES:BX</code> with a valid pointer to the symbol
<code>symbol</code>.</p>
<p>Things can be more complex than this: since 16-bit segments and groups
may overlap, you might occasionally want to refer to some symbol using a
different segment base from the preferred one. NASM lets you do this, by
the use of the <code>WRT</code> (With Reference To) keyword. So you can do
things like</p>
<pre>
        mov     ax,weird_seg        ; weird_seg is a segment base 
        mov     es,ax 
        mov     bx,symbol wrt weird_seg
</pre>
<p>to load <code>ES:BX</code> with a different, but functionally
equivalent, pointer to the symbol <code>symbol</code>.</p>
<p>NASM supports far (inter-segment) calls and jumps by means of the syntax
<code>call segment:offset</code>, where <code>segment</code> and
<code>offset</code> both represent immediate values. So to call a far
procedure, you could code either of</p>
<pre>
        call    (seg procedure):procedure 
        call    weird_seg:(procedure wrt weird_seg)
</pre>
<p>(The parentheses are included for clarity, to show the intended parsing
of the above instructions. They are not necessary in practice.)</p>
<p>NASM supports the syntax <code>call far procedure</code> as a synonym
for the first of the above usages. <code>JMP</code> works identically to
<code>CALL</code> in these examples.</p>
<p>To declare a far pointer to a data item in a data segment, you must code</p>
<pre>
        dw      symbol, seg symbol
</pre>
<p>NASM supports no convenient synonym for this, though you can always
invent one using the macro processor.</p>
<h3 id="section-3.7">3.7 <code>STRICT</code>: Inhibiting Optimization</h3>
<p>When assembling with the optimizer set to level 2 or higher (see
<a href="nasmdoc2.html#section-2.1.24">section 2.1.24</a>), NASM will use
size specifiers (<code>BYTE</code>, <code>WORD</code>, <code>DWORD</code>,
<code>QWORD</code>, <code>TWORD</code>, <code>OWORD</code>,
<code>YWORD</code> or <code>ZWORD</code>), but will give them the smallest
possible size. The keyword <code>STRICT</code> can be used to inhibit
optimization and force a particular operand to be emitted in the specified
size. For example, with the optimizer on, and in <code>BITS 16</code> mode,</p>
<pre>
        push dword 33
</pre>
<p>is encoded in three bytes <code>66 6A 21</code>, whereas</p>
<pre>
        push strict dword 33
</pre>
<p>is encoded in six bytes, with a full dword immediate operand
<code>66 68 21 00 00 00</code>.</p>
<p>With the optimizer off, the same code (six bytes) is generated whether
the <code>STRICT</code> keyword was used or not.</p>
<h3 id="section-3.8">3.8 Critical Expressions</h3>
<p>Although NASM has an optional multi-pass optimizer, there are some
expressions which must be resolvable on the first pass. These are called
<em>Critical Expressions</em>.</p>
<p>The first pass is used to determine the size of all the assembled code
and data, so that the second pass, when generating all the code, knows all
the symbol addresses the code refers to. So one thing NASM can't handle is
code whose size depends on the value of a symbol declared after the code in
question. For example,</p>
<pre>
        times (label-$) db 0 
label:  db      'Where am I?'
</pre>
<p>The argument to <code>TIMES</code> in this case could equally legally
evaluate to anything at all; NASM will reject this example because it
cannot tell the size of the <code>TIMES</code> line when it first sees it.
It will just as firmly reject the slightly paradoxical code</p>
<pre>
        times (label-$+1) db 0 
label:  db      'NOW where am I?'
</pre>
<p>in which <em>any</em> value for the <code>TIMES</code> argument is by
definition wrong!</p>
<p>NASM rejects these examples by means of a concept called a <em>critical
expression</em>, which is defined to be an expression whose value is
required to be computable in the first pass, and which must therefore
depend only on symbols defined before it. The argument to the
<code>TIMES</code> prefix is a critical expression.</p>
<h3 id="section-3.9">3.9 Local Labels</h3>
<p>NASM gives special treatment to symbols beginning with a period. A label
beginning with a single period is treated as a <em>local</em> label, which
means that it is associated with the previous non-local label. So, for
example:</p>
<pre>
label1  ; some code 

.loop 
        ; some more code 

        jne     .loop 
        ret 

label2  ; some code 

.loop 
        ; some more code 

        jne     .loop 
        ret
</pre>
<p>In the above code fragment, each <code>JNE</code> instruction jumps to
the line immediately before it, because the two definitions of
<code>.loop</code> are kept separate by virtue of each being associated
with the previous non-local label.</p>
<p>This form of local label handling is borrowed from the old Amiga
assembler DevPac; however, NASM goes one step further, in allowing access
to local labels from other parts of the code. This is achieved by means of
<em>defining</em> a local label in terms of the previous non-local label:
the first definition of <code>.loop</code> above is really defining a
symbol called <code>label1.loop</code>, and the second defines a symbol
called <code>label2.loop</code>. So, if you really needed to, you could
write</p>
<pre>
label3  ; some more code 
        ; and some more 

        jmp label1.loop
</pre>
<p>Sometimes it is useful &ndash; in a macro, for instance &ndash; to be
able to define a label which can be referenced from anywhere but which
doesn't interfere with the normal local-label mechanism. Such a label can't
be non-local because it would interfere with subsequent definitions of, and
references to, local labels; and it can't be local because the macro that
defined it wouldn't know the label's full name. NASM therefore introduces a
third type of label, which is probably only useful in macro definitions: if
a label begins with the special prefix <code>..@</code>, then it does
nothing to the local label mechanism. So you could code</p>
<pre>
label1:                         ; a non-local label 
.local:                         ; this is really label1.local 
..@foo:                         ; this is a special symbol 
label2:                         ; another non-local label 
.local:                         ; this is really label2.local 

        jmp     ..@foo          ; this will jump three lines up
</pre>
<p>NASM has the capacity to define other special symbols beginning with a
double period: for example, <code>..start</code> is used to specify the
entry point in the <code>obj</code> output format (see
<a href="nasmdoc8.html#section-8.4.6">section 8.4.6</a>),
<code>..imagebase</code> is used to find out the offset from a base address
of the current image in the <code>win64</code> output format (see
<a href="nasmdoc8.html#section-8.6.1">section 8.6.1</a>). So just keep in
mind that symbols beginning with a double period are special.</p>
</div>
</body>
</html>
